<!--

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

-->

<html>
<head>
<title>Explorer API</title>
<link rel="Stylesheet" href="@TOP@/resource-files/prose.css" type="text/css" title="NetBeans Open APIs Style">
</head>
<body>

<p class="overviewlink"><a href="@TOP@/index.html">Overview</a></p>

<h1>Javadoc</h1>

The basic management of the Explorer resides in

{@link org.openide.explorer org.openide.explorer }.

Classes pertaining to the Property Sheet (which displays properties of
explored nodes) may be found in

{@link org.openide.explorer.propertysheet org.openide.explorer.propertysheet }.

A set of standard Explorer Views is available in

{@link org.openide.explorer.view org.openide.explorer.view }.

<h1>Contents</h1>

<ul>

<li><a href="#overview">Overview of the Explorer</a>
<ul>
<li><a href="#intro-node">Explorer Views and Nodes</a>
</ul>

<li><a href="#use-expl">Using the Explorer</a>
<ul>
<li><a href="#show-expl">Displaying a new Explorer window</a>
<li><a href="#show-prop">Displaying a Property Sheet</a>
<li><a href="#node-aspect">Aspects of nodes affecting the Explorer</a>
</ul>

<li><a href="#cust-expl">Customizing the Explorer</a></li>

<li><a href="#propsheet">The Property Sheet</a>
<ul>
    <li><a href="#customps">Customizing the Property Sheet</a></li>
    <li><a href="#customeds">Property Editors</a></li>
</ul>
</li>
</ul>

<h1>Explorer API</h1>

<h2 id="overview">Overview of the Explorer</h2>

Explorer views are UI components which render <em>nodes</em> - the most 
prominent in NetBeans being the Project and Files tabs on the left side of
the main window.  The Explorer API provides UI components to render nodes
in trees, lists, combo boxes, menus, tree tables.  These components 
handle things like cut/copy/paste, drag and drop, displaying popup menus
for nodes, which contain the actions the clicked node provides from
<code>getActions()</code>.

<h3 id="intro-node">The Explorer and Nodes</h3>

An Explorer view is solely a user-interface component: it has no particular 
knowledge of <i>what</i> it is displaying.  Rather, it provides the 
physical user interface for a hierarchy of Nodes, as described in the 
<a href="@org-openide-nodes@/org/openide/nodes/doc-files/api.html">Nodes API</a>.

<p>A given Explorer view instance will be some visual component (such as a
Swing panel) displaying some representation of a Node and its children.
The topmost node being displayed is said to
be the <em>root</em> of the Explorer. 

<p>The API permits you to use the prebuilt views, and also to <a href="customExplorerViews.html">create
your own</a> if you need to.

<h2 id="use-expl">Using the Explorer API</h2>

It is rather easy to use the Explorer API to just display an Explorer
window of some type, browsing some set of nodes.

<h3 id="show-expl">Displaying a new Explorer window</h3>

Probably the easiest way to show an Explorer window is just to call
{@link org.openide.nodes.NodeOperation#explore(org.openide.nodes.Node) NodeOperation.explore(...) }.

This will simply show a node and its subtree (if any) in a new window
using the normal tree-style Explorer view. It does not permit any
customization of the UI, however - it creates a standard window with
the usual buttons, etc.

<p>If you want to use a special view, it is first necessary to
understand the structure of a live Explorer instance:

<ol>

<li>There is a <em>topmost container</em>, an AWT/Swing container
component of any sort, which must implement

{@link org.openide.explorer.ExplorerManager.Provider ExplorerManager.Provider }.
Often in NetBeans it will be a subclass of <a href="@org-openide-windows@/org/openide/windows/TopComponent.html">TopComponent</a>.

This topmost container does not really do anything; it just makes sure
that an <code>ExplorerManager</code> can be found by its
children. Follow the instructions in 

{@link org.openide.explorer.ExplorerUtils ExplorerUtils },

to create such a panel.
<!-- XXX tboudreau - factor ExplorerPanel into some explorerhelper API that
     depends on Winsys & Explorer - this is really silly -->

The container that implements ExplorerManager.Provider may contain
non-Explorer components - add whatever components you like to it, set
layout appropriately.  When an Explorer view is added as a descendant
of this panel, it will find this panel by searching the component 
hierarchy.



{@link org.openide.explorer.ExplorerManager ExplorerManager }

itself handles the control of the Explorer view or views it is
attached to. It provides the external interface by which the selection
of nodes, e.g., can be examined or set, and permits multiple views to
be synchronized (for example, creating a master/detail view is very easy). 

<li>Usually, actions provided by {@link org.openide.explorer.ExplorerUtils ExplorerUtils },
will be attached to the component to make sure they are correctly enabled
or disabled according to the current node selection. Follow the example in
{@link org.openide.explorer.ExplorerUtils ExplorerUtil }.



<li>Most importantly, the Explorer views themselves are added as
(possibly indirect) children to the topmost component. You do
<em>not</em> need to do anything special to connect the views to the
manager or to one another; when an explorer view is added to a container,
it will find the nearest ExplorerManager in the component hierarchy
(by searching for a parent component that implements ExplorerManager.Provider).
<p>
Once you have created an Explorer component, your code will not typically
interact directly with it - rather it will call methods on its ExplorerManager
to set selection, etc.</li>

<li>Lastly you'll call {@link org.openide.explorer.ExplorerManager#setRootContext(org.openide.nodes.Node) ExplorerManager.setRootContext }
to actually set what node the view will be displaying.
</li>

</ol>

{@link org.openide.explorer.view org.openide.explorer.view }

contains a number of prebuilt views which you may use. Of special note
are the

{@link org.openide.explorer.view.BeanTreeView BeanTreeView },

which is the standard tree view used to implement the Explorer window
proper;

and

{@link org.openide.explorer.view.MenuView MenuView },

which is of interest because it actually implements a view using popup
menus, rather than a static display. The best way to familiarize
yourself with the standard views, and to test any custom view you
might build, is probably to create an <code>ExplorerPanel</code> which
adds some or all of them; the views will be automatically
synchronized, which will be helpful in understanding how they behave.

<h3 id="show-prop">Displaying a Property Sheet</h3>

Adding a <em>Property Sheet</em> (which just shows the properties of
the selected node(s), and may allow editing of those properties) is
quite easy - all you need to do is to add a

{@link org.openide.explorer.propertysheet.PropertySheetView PropertySheetView }

to the container. It is an Explorer view which does not actually
display any nodes, but rather displays a list of properties for the
node or nodes which are selected according to the ExplorerManager.

<p>Since views by default will share the same manager if they are
added to the same manager-providing container, just adding a regular
Explorer view and a Property Sheet to the same container will result
in the Property Sheet being sensitive to the node selection in the
regular view, which is usually the desired effect.

<h3 id="node-aspect">Aspects of Nodes affecting the Explorer</h3>

Particular Explorer views are of course free to display the node
hierarchy any way they wish; however, there are a few common aspects
of the represented nodes which are likely to be visually mirrored:

<ul>

<li>The node's

{@link java.beans.FeatureDescriptor#getDisplayName() display name }

and

{@link java.beans.FeatureDescriptor#getShortDescription() short description }

ought to be used by views to display the node and provide (e.g.) tool tips.

<li>The

{@link org.openide.nodes.Node#getIcon(int) icon}

is used in most views alongside the display name. Non-leaf nodes upon
expansion will show the

{@link org.openide.nodes.Node#getOpenedIcon(int) opened icon }.

<li>Some or all of the node's

{@link org.openide.nodes.Node#getChildren() children}

are typically displayed (except of course if it is a

{@link org.openide.nodes.Node#isLeaf() leaf }).

Normally they will be in the same order as
the node itself

{@link org.openide.nodes.Children#getNodes() specifies },

though a view might provide special display characteristics for
certain children lists such as

{@link org.openide.nodes.Children.Keys Children.Keys }.

Generally nodes may allow their children to be

{@link org.openide.nodes.Index reordered }.

<li>{@link org.openide.nodes.Node#getActions() Node.getActions() },

{@link org.openide.nodes.Node#getContextActions() Node.getContextActions() },

{@link org.openide.nodes.Node#getDefaultAction() Node.getDefaultAction() },

{@link org.openide.nodes.Node#getContextMenu() Node.getContextMenu() },

etc. are typically used to build an event-handling system for the
visual representation of the nodes.

<li>Standard actions are generally enabled on nodes in the Explorer,
so that

{@link org.openide.nodes.Node#hasCustomizer() Node.hasCustomizer() },

{@link org.openide.nodes.Node#getLookup() Node.getLookup().lookup(...) },

{@link org.openide.nodes.Node#getNewTypes() Node.getNewTypes() },

{@link org.openide.nodes.Node#getPasteTypes(java.awt.datatransfer.Transferable) Node.getPasteTypes(...) },

and so on affect other UI components (such as toolbars) which may hold
action presenters.

<li>{@link org.openide.nodes.Node#getPropertySets() Node.getPropertySets() }

is of course used by the Property Sheet view.

<li>Some views may provide in-place editing commands (not relying on
system actions present in popup menus, e.g.) for moving nodes,
renaming them in place, etc. - these will use the standard node hooks
such as

{@link org.openide.nodes.Node#canRename() Node.canRename() },

{@link org.openide.nodes.Node#cloneNode() Node.cloneNode() },

or

{@link org.openide.nodes.Node#clipboardCut() Node.clipboardCut() }.

</ul>

<h2 id="cust-expl">Customizing the Explorer</h2>
Though rarely necessary, the API allows you to create your own Explorer views,
as described <a href="customExplorerViews.html">here</a>.

<h2 id="propsheet">The Property Sheet</h2>
Older versions of NetBeans relied heavily on the Property Sheet as a primary
element of the user interface.  However, this turned out not to be terribly
user-friendly, and the Property Sheet is used considerably less today (it is
no longer even displayed by default on startup).
<p>
Consider providing a custom UI where possible, rather than relying on the
user having the Property Sheet visible to work with your module.

<h3 id="customps">Customizing the Property Sheet</h3>

<div class="nonnormative">
The Property Sheet displays property sets in expandable
categories inside a single tree, rather than using tabs as the old
Property Sheet did.  However, there are some cases where tabs are
desirable.  A mechanism exists by which an instance of
<code>Node.PropertySet</code> can specify that it should be displayed in
a tab:  It must return an internationalized string from
<code>PropertySet.getValue(&quot;tabName&quot;)</code>.  If multiple
property sets belonging to a single node specify the same tab name
in this manner, all of them will be included on a tab with the specified
name <em>*</em>.

<blockquote>
    <em>*</em>
Note that for this functionality to function properly, the
NetBeans Window System must be installed.  Further information on how to
work use this functionality in a stand-alone application can be found
<a href="propertySheetReference.html#tabs">here</a>.
</blockquote>
</div>

A number of system properties, UI manager keys and such also affect
the way Property Sheets are displayed and behave.  A complete reference
can be found <a href="propertySheetReference.html">here</a>.

<h3 id="customeds">Property Editors</h3>
The NetBeans core installs a variety of property editors for standard JDK
classes and some NetBeans classes.  A number of these can have their behavior
altered by passing &quot;hints&quot; from <code>Node.Property</code> or
<code>PropertyDescriptor</code>.  This is described in detail
<a href="propertyViewCustomization.html">here</a>.

<hr>@FOOTER@
</body>
</html>
